Migration Guide v1 to v2

This guide will help you migrate your Context API integration from v1 to v2. The v2 API introduces a more structured and flexible approach to content processing with improved type safety and clearer action configurations.

Overview of Changes

Key Differences

Aspect	v1 Format	v2 Format
Version Field	null or "context.api/v1"	"context.api/v2" (required)
Object Keys	Array of strings	Array of objects with path property
Actions	Array of strings (kebab-case)	Object with action keys (camelCase)
Action Naming	kebab-case	camelCase
Instructions	Top-level, optional, and will apply for any action except generate embeddings	Nested in action objects, for all actions except generate embeddings

Benefits of v2

• Structured Actions: Each action can have its own configuration
• Type Safety: Clear object structure reduces errors
• Flexibility: Actions can be configured independently
• Extensibility: Easier to add new properties per action
• Clarity: Instructions are colocated with their actions

Migration Steps

Step 1: Update Version Field

Add or update the version field to use v2:

v1:

{
  "version": null
}

or

{
  "version": "context.api/v1"
}

v2:

{
  "version": "context.api/v2"
}

Step 2: Convert Object Keys

Transform the object keys array from strings to objects:

v1:

{
  "objectKeys": [
    "documents/123/contract.pdf",
    "documents/123/invoice.pdf"
  ]
}

v2:

{
  "objectKeys": [
    {
      "path": "documents/123/contract.pdf"
    },
    {
      "path": "documents/123/invoice.pdf"
    }
  ]
}

Step 3: Convert Actions to camelCase

Update action names from kebab-case to camelCase:

v1 Action Name	v2 Action Name
text-summarization	textSummarization
text-metadata-generation	textMetadataGeneration
text-embeddings	textEmbeddings
text-classification	textClassification
named-entity-recognition-text	namedEntityRecognitionText
image-description	imageDescription
image-metadata-generation	imageMetadataGeneration
image-embeddings	imageEmbeddings
image-classification	imageClassification
named-entity-recognition-image	namedEntityRecognitionImage

v1:

{
  "actions": [
    "text-summarization",
    "text-embeddings"
  ]
}

v2:

{
  "actions": {
    "textSummarization": {},
    "textEmbeddings": {}
  }
}

Step 4: Structure Actions with Configurations

Move action-specific configurations from top-level to action object values:

v1:

{
  "actions": ["text-classification"],
  "classes": ["invoice", "contract", "other"],
  "instructions": {
    "context": "legal documents"
  }
}

v2:

{
  "actions": {
    "textClassification": {
      "classes": ["invoice", "contract", "other"],
      "instructions": {
        "context": "legal documents"
      }
    }
  }
}

Note: In v2, instructions can only be provided for imageClassification, textClassification, imageMetadataGeneration, and textMetadataGeneration actions.

Complete Migration Examples

Example 1: Text Summarization

v1:

{
  "version": "context.api/v1",
  "objectKeys": [
    "documents/123/report.pdf"
  ],
  "actions": [
    "text-summarization"
  ],
  "maxWordCount": 200,
  "instructions": {
    "tone": "professional"
  }
}

v2:

{
  "version": "context.api/v2",
  "objectKeys": [
    {
      "path": "documents/123/report.pdf"
    }
  ],
  "actions": {
    "textSummarization": {
      "maxWordCount": 200
    }
  }
}

Example 2: Text Classification

v1:

{
  "version": "context.api/v1",
  "objectKeys": [
    "documents/456/contract.pdf"
  ],
  "actions": [
    "text-classification"
  ],
  "classes": [
    "invoice",
    "contract",
    "receipt",
    "other"
  ],
  "instructions": {
    "context": "legal documents"
  }
}

v2:

{
  "version": "context.api/v2",
  "objectKeys": [
    {
      "path": "documents/456/contract.pdf"
    }
  ],
  "actions": {
    "textClassification": {
      "classes": [
        "invoice",
        "contract",
        "receipt",
        "other"
      ],
      "instructions": {
        "context": "legal documents"
      }
    }
  }
}

Example 3: Text Metadata Generation

v1:

{
  "version": "context.api/v1",
  "objectKeys": [
    "documents/789/legal-doc.pdf"
  ],
  "actions": [
    "text-metadata-generation"
  ],
  "kSimilarMetadata": [
    {
      "document:type": "Legal Contract|Agreement|NDA",
      "document:category": "Corporate|Personal|Employment",
      "keywords:tags": "confidentiality|non-disclosure|legal"
    }
  ],
  "instructions": {
    "detailLevel": "high"
  }
}

v2:

{
  "version": "context.api/v2",
  "objectKeys": [
    {
      "path": "documents/789/legal-doc.pdf"
    }
  ],
  "actions": {
    "textMetadataGeneration": {
      "kSimilarMetadata": [
        {
          "document:type": "Legal Contract|Agreement|NDA",
          "document:category": "Corporate|Personal|Employment",
          "keywords:tags": "confidentiality|non-disclosure|legal"
        }
      ],
      "instructions": {
        "detailLevel": "high"
      }
    }
  }
}

Example 4: Image Classification

v1:

{
  "version": "context.api/v1",
  "objectKeys": [
    "images/vehicle-photo.jpg"
  ],
  "actions": [
    "image-classification"
  ],
  "classes": [
    "damaged_vehicle",
    "undamaged_vehicle",
    "not_a_vehicle"
  ],
  "instructions": {
    "focus": "vehicle damage assessment"
  }
}

v2:

{
  "version": "context.api/v2",
  "objectKeys": [
    {
      "path": "images/vehicle-photo.jpg"
    }
  ],
  "actions": {
    "imageClassification": {
      "classes": [
        "damaged_vehicle",
        "undamaged_vehicle",
        "not_a_vehicle"
      ],
      "instructions": {
        "focus": "vehicle damage assessment"
      }
    }
  }
}

Example 5: Multiple Actions with Different Instructions

v1:

{
  "version": "context.api/v1",
  "objectKeys": [
    "documents/meeting-notes.pdf"
  ],
  "actions": [
    "text-summarization",
    "text-classification",
    "text-embeddings"
  ],
  "maxWordCount": 150,
  "classes": [
    "meeting",
    "report",
    "memo",
    "other"
  ],
  "instructions": {
    "context": "business meeting notes"
  }
}

v2:

{
  "version": "context.api/v2",
  "objectKeys": [
    {
      "path": "documents/meeting-notes.pdf"
    }
  ],
  "actions": {
    "textSummarization": {
      "maxWordCount": 150
    },
    "textClassification": {
      "classes": [
        "meeting",
        "report",
        "memo",
        "other"
      ],
      "instructions": {
        "context": "business meeting notes"
      }
    },
    "textEmbeddings": {}
  }
}

Example 6: Image Processing with Multiple Actions

v1:

{
  "version": "context.api/v1",
  "objectKeys": [
    "photos/product-image.jpg"
  ],
  "actions": [
    "image-description",
    "image-metadata-generation",
    "image-embeddings"
  ],
  "maxWordCount": 100,
  "kSimilarMetadata": [
    {
      "product:name": "T-Shirt|Shoes|Hat|Jacket",
      "product:color": "Red|Blue|Green|Black|White",
      "product:category": "Clothing|Footwear|Accessories",
      "keywords:tags": "fashion|apparel|retail"
    }
  ],
  "instructions": {
    "style": "detailed product description"
  }
}

v2:

{
  "version": "context.api/v2",
  "objectKeys": [
    {
      "path": "photos/product-image.jpg"
    }
  ],
  "actions": {
    "imageDescription": {
      "maxWordCount": 100
    },
    "imageMetadataGeneration": {
      "kSimilarMetadata": [
        {
          "product:name": "T-Shirt|Shoes|Hat|Jacket",
          "product:color": "Red|Blue|Green|Black|White",
          "product:category": "Clothing|Footwear|Accessories",
          "keywords:tags": "fashion|apparel|retail"
        }
      ],
      "instructions": {
        "style": "detailed product description"
      }
    },
    "imageEmbeddings": {}
  }
}

Validation Changes

v2 Validation Rules

1. Version Required: When using v2 format, version: "context.api/v2" is mandatory
2. Structured Format: Cannot mix v1 string format with v2 object format
3. Action-Specific Instructions: Instructions can only be provided for imageClassification, textClassification, imageMetadataGeneration, and textMetadataGeneration actions
4. Case Sensitivity: Action names must use camelCase in v2

Backward Compatibility

v1 Support

The Context API continues to support v1 format. You can:

• Use version: null or version: "context.api/v1"
• Continue using string arrays for objectKeys and actions
• Use kebab-case action names
• Keep top-level classes, maxWordCount, and kSimilarMetadata properties

When to Migrate

Consider migrating to v2 when:

• You need to use different instructions for different actions
• You want better type safety and validation
• You're building new integrations
• You need clearer, more maintainable code

No Immediate Deprecation

There is no immediate deprecation planned for v1. You can migrate at your own pace.

Testing Your Migration

1. Test with Simple Payload

Start with a basic request:

{
  "version": "context.api/v2",
  "objectKeys": [
    {"path": "test/sample.pdf"}
  ],
  "actions": {
    "textEmbeddings": {}
  }
}

2. Add Instructions Gradually

Test each action type:

{
  "version": "context.api/v2",
  "objectKeys": [{"path": "test/sample.pdf"}],
  "actions": {
    "textSummarization": {
      "maxWordCount": 100
    }
  }
}

3. Validate Error Messages

Intentionally trigger validation to understand error messages. For example, test classification without required classes property to see validation feedback.

Getting Help

If you encounter issues during migration:

1. Check the v2 API Examples for reference
2. Review Supported Actions
3. Consult the OpenAPI specification
4. Contact the Context API support team

Summary

The v2 API provides a more structured and flexible approach to content processing. While migration requires updates to your request format, the benefits include:

• Better organization of action-specific parameters
• Improved type safety
• Greater flexibility for future enhancements
• Clearer, more maintainable integration code

Take your time with the migration, test thoroughly, and reach out if you need assistance.